# Appendix B. Perl Modules

#### Contents:

CPAN
perldoc

This book discusses many Perl modules that may not be included with your system. This appendix contains instructions for installing modules from CPAN. It also discusses how to use perldoc to access documentation.

## B.1. CPAN

CPAN is the Comprehensive Perl Archive Network, found at http://www.cpan.org/ and at numerous mirrors around the world (see http://www.cpan.org/SITES.html). From CPAN you can download source code and binary distributions of Perl, plus all of the modules we mentioned in this book and many other scripts and modules.

You can browse the very long list of modules at http://www.cpan.org/modules/00modlist.long.html. If you know the name of a module you wish to download, then you can generally find it via the first word of the module's name. For example, you can download Digest::MD5 from http://www.cpan.org/modules/by-module/Digest/. The filename within that directory is Digest-MD5-2.09.tar.gz (note that the version number, 2.09, will likely change by the time you read this book).

### B.1.1. Installing Modules

All Perl modules distributed on CPAN follow a consistent install process, but some modules are easier to install than others. Some have dependencies on other modules, and some include C source code that must be compiled and often linked to other libraries on your system.

You may have difficulty compiling the modules that contain C code. Most commercial distributions of Unix do not include an ANSI C compiler. You can generally obtain a prebuilt binary of the `gcc` compiler instead. Check software archive sites specific to your platform (for example, http://www.sun.com/sunsite/ for Solaris and http://hpux.cae.wisc.edu/ for HP/UX). Linux and BSD systems should already have the tools you need.

If you are using ActiveState's release of Perl on Win32, then you can use the Perl Package Manager to download pre-built binary modules from ActiveState. Visit http://www.activestate.com/PPM/ for more information.

The simplest way to install modules on Unix and compatible systems is to use the CPAN.pm module. You can invoke it like this, typically as the superuser:

>     # perl -MCPAN -e shell

It creates an interactive shell, from which you to get information about modules on CPAN and install or update modules on your system. The first time you run CPAN, it will prompt you for configuration information that tells it what tools are available for downloading modules, and what CPAN mirrors to use.

Once CPAN is configured, you can install a module by simply typing `install` followed by the name of the module:

>     cpan> install Digest::MD5

CPAN will fetch the requested module and install it. CPAN recognizes dependencies on other modules and will automatically install required modules for you. There are several other commands available besides `install`; you can get a full list by entering a question mark at the prompt.

Occasionally, CPAN will not be able to install a module for you. In that case, you will have to install a module manually. On Unix and compatible systems, you should use the following steps after you have downloaded a module:

>     $ gzip -dc Digest-MD5-2.09.tar.gz | tar xvf -
>     $ cd Digest-MD5-2.09
>     $ perl Makefile.PL
>     $ make
>     $ make test
>     $ su
>     # make install

If `make` or `make test` fails, then you will need to find and fix the problem. Check the documentation included with the module for assistance. If the module you have downloaded contains C code that links to other libraries, verify that the versions of your libraries match what the Perl module expects. You might also search past newsgroup postings for anyone who already encountered and solved the same problem. You can use http://www.deja.com/usenet/ for this; navigate to the advanced news search and search comp.lang.perl.modules for related terms.

If you have verified any version dependencies, cannot find any answers in the documentation, cannot find any answers in past newsgroup postings, and cannot solve the problem yourself, then post a polite, detailed message to news:comp.lang.perl.modules explaining the problem and asking for assistance. You probably should not use deja.com for this, however. Unfortunately, some of the most knowledgeable and helpful Perl coders filter out news messages posted from deja.com (for the same reason, you may want to avoid sending your message from a Microsoft mail application, too).

Copyright © 2001 O'Reilly & Associates. All rights reserved.